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Abstract 

Generic Fortran common blocks are presented for use by High Energy Physics 
event generators for the transfer of event configurations from parton level generators 
to showering and hadronization event generators. 

Modularization of High Energy Particle Physics event generation is becoming increasingly 
useful as the complexity of Monte Carlo programs grows. To accommodate this trend, several 
authors of popular Monte Carlo and matrix element programs attending the Physics at Te V 
Colliders Workshop in Les Houches, 2001 have agreed on a generic format for the transfer of 
parton level event configurations from matrix element event generators (MEG) to showering 
and hadronization event generators (SHG). 

CompHEP [0] 

Grace [|] Herwig || 

MadGraph [|] Isajet 

VecBos [| Pythia § 

WbbGen jj 



Events generated this way are customarily called user (or user-defined) processes, to 
distinguish them from the internal processes that come with the SHG. Specific solutions 
are already in use, including an interface of WbbGen with Herwig || and an interface of 



CompHEP with Pythia |TI| — that experience is exploited here. 



An implementation of the user process interface has been included in Pythia 6.2, described 



(with an example) in Ref. fTT 



The user process interface discussed here is not intended as a replacement for HEPEVT flT2"| , 
which is the standard Fortran common block for interface between generators and analy- 
sis/detector simulation. The user process common blocks address the communication be- 
tween two event generators only, a MEG one and a SHG one, and not the communication 
of event generators with the outside world. 

In the course of a normal event generation run, this communication occurs at two stages: 
(1) At initilization, to establish the basic parameters of the run as a whole. (2) For each 
new event that is to be transferred from the MEG to the SHG. Each of these two stages 
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here corresponds to its own Fortran common block.Q These common blocks are described in 
detail in the next two sections, followed by some examples. 

One can also foresee that each stage will be associated with its own subroutine, called 
from the SHG, where information is put in the respective common block, based on output 
from the MEG. The details of these subroutines are likely to be specific to a given MEG 
and may also be specific to a given SHG. The subroutine names UPINIT and UPEVNT (each 
with no arguments) were chosen for the Pythia 6.2 implementation. They are intended to be 
generic (the usual PY prefixes are omitted), and only dummy versions are packaged with the 
program. It is recommended that other SHG authors use the same dummy routine names 
(with zero arguments) such that for simple cases which do not require intervention 'by hand', 
MEG authors will be able to interface several SHGs with a single set of routines. Example 



routines are presented in the Pythia documentation JTT] . 

In general, a user process run may consist of a number of subprocesses, each denoted 
by a unique integer identifier. If the user wishes to have the SHG unweight events using 
acceptance-rejection and/or mix together events from different processes, then the user pro- 
cess author will need to supply a subroutine that is able to return an event of the requested 
subprocess type to the SHG on demand. The author may choose to organize the subroutine 
to generate the event 'on the fly', or to read the event from a file stream (with a separate 
file stream for each subprocess). The SHG will also need information about the subprocess 
cross section and/or maximum event weight to select which process is generated next and 
for acceptance-rejection. This information will need to be known from the onset (and could, 
for example, be determined in advance from an initialization run). Alternatively, the user 
may already have a proper mixture of subprocesses from the MEG and only wish the SHG 
to process events in the order they are handed in. We therefore allow for several different 
event weight models. 

If extra information is needed for a specific user implementation, then a implementation- 
specific common block should be created. The meaning of the user process common block 
elements should not be overloaded, as this would defeat the generic purpose. 

The descriptions in this paper are intended for event generator authors and may appear 
complex — most of the details will be transparent to the casual user. 



1 'User Process' Run Information 

The run common block contains information which pertains to a collection of events. 
In general this information is process dependent and it is impossible to include everything in 
a generic common block. Instead only the most general information is included here, and it 
is expected that users will have to intervene 'by hand' for many cases (i.e. a user may need 
to specify which cutoffs are used to avoid singularities, which jet clustering algorithm has 
been used to recombine partons in a next-to-leading-order calculation, the effective parton 
masses, . . . ). 

1 An interface in C++ has been developed in Ref. |l3| and contains similar information content as that 
discussed here. 
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integer MAXPUP 
parameter ( MAXPUP=100 ) 

integer IDBMUP, PDFGUP, PDFSUP, IDWTUP, NPRUP, LPRUP 

double precision EBMUP , XSECUP, XERRUP, XMAXUP 

common /HEPRUP/ IDBMUP(2), EBMUP(2), PDFGUP(2), PDFSUP(2), 

+ IDWTUP, NPRUP , XSECUP (MAXPUP) , XERRUP (MAXPUP) , 

+ XMAXUP (MAXPUP) , LPRUP (MAXPUP) 



HEPRUP 'User Process' Run Common Block 

• parameter MAXPUP=100 : maximum number of different processes to be interfaced at one 
time 

Beam Information 



Beam particle 1 (2) is defined as traveling along the +Z (-Z) direction. 

integer IDBMUP (2) : ID of beam particle 1 and 2 according to the Particle Data Group 
convention j fl^l/ 

double EBMUP (2) : energy in GeV of beam particles 1 and 2 



• integer PDFGUP(2) : the author group for beam 1 and 2, according to the Cernlib PDFlib [15 J 
specification 

» integer PDFSUP (2) : the PDF set ID for beam 1 and 2, according to the Cernlib PDFlib 
specification 

For e+e" or when the SHG defaults are to be used, PDFGUP=-1, PDFSUP=~1 should be 
specified. 

The PDFlib enumeration of PDFs is sometimes out of date, but it is the only unique integer 
labels for PDFs available. In the case where a PDF not included in PDFlib is being used, 
this information will have to be passed 'by hand'. 

Process Information 



• integer IDWTUP : master switch dictating how the event weights (XWGTUP) are interpreted 
The user is expected to pick the most appropriate event weight model for a run, given the 
MEG input at hand and the desired output. Normally the SHG should be able to handle all 
of the models. 

A summary of the IDWTUP switches is presented in Table |l|. 

+1 Events are weighted on input and the SHG is asked to produce events with weight +1 
as output. XSECUP and XERRUP need not be provided, but are calculated by the 
SHG. XWGTUP is a dimensional quantity, in pb, with a mean value converging to the 
cross section of the process. The SHG selects the next subprocess type to be generated, 
based on the relative size of the XMAXUP (i) values. The user-supplied interface routine 
must return an event of the requested type on demand from the SHG, and the maxi- 
mum weight XMAXUP (or a reasonable approximation to it) must be known from the 
onset. A given event is accepted with a probability XWGTUP /XMAXUP (i). In case 
of rejection, a new event type and a new event are selected. If XMAXUP (i) is chosen 
too low, such that XWGTUP violates the XMAXUP (i), the SHG will issue a warning 
and update XMAXUP(i) with the new maximum weight value. If events of some types 
are already available unweighted, then a correct mixing of these processes is ensured by 
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putting XWGTUP = XMAXUP(i). In this option also the internal SHG processes are 
available, and can be mixed with the external ones. All weights are positive definite, 
/c-factors may be included on an event by event basis by the user process interface by 
re-scaling the XWGTUP for each event. 

-1 Same as above (IDWTUP=+1), but the event weights may be either positive or negative 
on input, and the SHG will produce events with weight +1 or -1 as output.^] A given 
event would be accepted with a probability |XWGTUP|/|XMAXUP(i)| and assigned 
weight sign(l, XWGTUP), where the sign function transfers the sign of XWGTUP 
onto 1. A physics process with alternating cross section sign must be split in two ID- 
PRUP types^j based on the sign of the cross section, such that all events of a particular 
IDPRUP have the same event weight sign. Also the XMAXUP(i) values must be avail- 
able for these two IDPRUP types separately, so that |XMAXUP(i)| gives the relative 
mixing of event types, with event acceptance based on |XWGTUP|/|XMAXUP(i)|. 

+2 Events are weighted on input and the SHG is asked to produce events with weight 
+ 1 as output. The SHG selects the next subprocess type to be generated, based on 
the relative size of the XSECUP(i) values. The user-supplied interface routine must 
return an event of the requested type on demand from the SHG. The cross sections 
XSECUP(i) must be known from the onset. A given event is accepted with a probability 
XWGTUP/XMAXUP(i). In case of rejection, a new event of the same type would be 
requested. In this scenario only the ratio XWGTUP/XMAXUP(i) is of significance. If 
events of some types are already available unweighted, then a correct mixing of these 
processes is ensured by putting XWGTUP = XMAXUP(i). A /c-factor can be applied 
to each process by re-scaling the respective XSECUP(i) value at the beginning of the 
run, but cannot be given individually for each event. In this option also the internal 
SHG processes are available, and can be mixed with the user processes. 

-2 Same as above (IDWTUP=+2), but the event weights may be either positive or negative 
on input, and the SHG will produce events with weight +1 or -1 as output. A physics 
process with alternating cross section sign must therefore be split in two IDPRUP types, 
based on the sign of the cross section, such that all events of a particular IDPRUP have 
the same event weight sign. Also the XSECUP(i) and XMAXUP(i) values must be avail- 
able for these two IDPRUP types separately, so that |XSECUP(i)| gives the relative mix- 
ing of event types, with event acceptance based on |XWGTUPj/|XMAXUP(i)| and the 
total cross section of the two IDPRUP types combined given by XSECUP(i)+XSECUP(j). 

+3 Events are unweighted on input such that all events come with unit weight XWGTUP=+1. 
The SHG will only ask for the next event. If any mixing or unweighting is desired, it 
will have to be performed by the user process interface. The SHG will not reject any 

2 Negative- weight events may occur e.g. in next-to-leading-order calculations. They should cancel against 
positive- weight events in physical distributions. The details of this cancellation arc rather subtle when 
considered in the context of showers and hadronization, however, and a proper treatment would require 
more information than discussed here. The negative-weight options should therefore be used with some 
caution, and the negative-weight events should be a reasonably small fraction of the total event sample. 

3 The motivation for this requirement is best understood with a simple example: imagine two subprocesses 
with the same cross section. The first process includes events with both positive and negative event weights 
such that two events out of three have weight +1 and the third -I. All events from the second process have 
positive weight +1. In this scenario these two processes should be 'mixed' with proportions 3:1 to account 
for the cancellations that occur for the first process. The proportions for the mixing are communicated to 
the SHG by supplying the positive and negative contributions to the cross section separately. 
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events (unless it encounters other kinds of problems). If a /c-factor is desired, it is the 
responsibility of the user process interface. When events are read sequentially from an 
already existing file, this would imply one common fc-factor for all processes. In this 
option it is not possible to mix with internal SHG processes. 

-3 Same as above (IDWTUP=+3), but the event weights may be either +1 or -1 on 
input. A single process identifier (IDPRUP) may include events with both positive and 
negative event weights. 

+4 Same as (IDWTUP=+3), but events are weighted on input and the average of the 
event weights (XWGTUP) is the cross section in pb. When histogramming results on 
analyzed events, these weights would have to be used. The SHG will only ask for the 
next event and will not perform any mixing or unweighting. Neither XSECUP nor 
XMAXUP needs to be known or supplied. In this option it is not possible to mix with 
internal SHG processes. 

-4 Same as (IDWTUP=+4), but event weights may be either positive or negative on input 
and the average of the event weights (XWGTUP) is the cross section. A single process 
identifier (IDPRUP) may include events with both positive and negative event weights. 
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Table 1: Summary of the options available for the master weight switch IDWTUP. 

• integer NPRUP : the number of different user subprocesses 

i.e. LPRUP and other arrays will have NPRUP entries, LPRUP(1:NPRUP) 

• double XSECUP (J) : the cross section for process J in pb 
This entry is mandatory for IDWTUP=±2. 

• double XERRUP(J) : the statistical error associated with the cross section of process J in 
pb 

It is not expected that this information will be used by the SHG, except perhaps for printouts. 

• double XMAXUP (J) : the maximum XWGTUP for process J 

For the case of weighted events (IDWTUP=±1,±2), this entry is mandatory — though it need 
not be specified to a high degree of accuracy. If too small a number is specified, the SHG will 
issue a warning and increase XMAXUP(J). This entry has no meaning for IDWTUP=±3,±4. 

• integer LPRUP(J) : a listing of all user process IDs that can appear in IDPRUP of HEPEUP 
for this run 

When communicating between the user process and SHG, the LPRUP code will be used. 
Example: if LPRUP(1)=1022, then the SHG will ask for an event of type 1022, not 1. 
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'User Process' Event Information 



integer MAXNUP 
parameter ( MAXNUP=500 ) 

integer NUP, IDPRUP, IDUP, ISTUP, MOTHUP, ICOLUP 
double precision XWGTUP, SCALUP, AQEDUP , AQCDUP, 



+ 



PUP, VTIMUP, SPINUP 
common /HEPEUP/ NUP, IDPRUP, XWGTUP, SCALUP, AQEDUP, AQCDUP , 



+ 



+ 



+ 



IDUP (MAXNUP) , ISTUP (MAXNUP) , MOTHUP (2 , MAXNUP) , 
ICOLUP (2, MAXNUP) , PUP (5, MAXNUP ) , VTIMUP (MAXNUP) , 
SPINUP (MAXNUP) 



HEPEUP 'User Process' Event Common Block 

• parameter MAXNUP=500 : maximum number of particle entries 

• integer NUP : number of particle entries in this event 

An event with NUP=0 denotes the case where the user process is unable to provide an event 
of the type requested by the SHG (i.e. if the user process is providing events to the SHG by 
reading them sequentially from a file and the end of the file is reached). 

• integer IDPRUP : ID of the process for this event 

The process ID's are not intended to be generic. The entry is a hook which the event 
generators can use to translate into their own scheme, or use in print statements (e.g. so that 
cross section information can be shown per process). 

When IDWTUP= ±1, ±2 the next process to be generated is selected by the SHG, and so 
IDPRUP is set by the SHG. For IDWTUP= ±3, ±4 the process is selected by the MEG, and 
IDPRUP is set by the MEG. 

• double XWGTUP : event weight 

weighted events: if the user process supplies weighted events and the SHG is asked to produce 
unweighted events, this number will be compared against XMAXUP in the run common block 
HEPRUP for acceptance-rejection. 

unweighted events: if the user process supplies events which have already been unweighted, 
this number should be set to +1 (-1 for negative weight events in e.g. a NLO calculation). 

The precise definition of XWGTUP depends on the master weight switch IDWTUP in the 
run common block. More information is given there. 

• double SCALUP : scale of the event in GeV, as used for calculation of PDFs 

If the scale has not been defined, this should be denoted by setting the scale to -1. 

• double AQEDUP : the QED coupling ckqed used for this event (e.g. 

• double AQCDUP : the QCD coupling «qcd used for this event 

When oqed and/or oqcd is not relevant for the process, or in the case where the user 
process prefers to let the SHG use its defaults, AQEDUP=-1 and/or AQCDUP=-1 should 
be specified. 

ID, Status, and Parent-Child History 

• integer IDUP (I) : particle ID according to Particle Data Group convention |7^ / 
undefined (and possibly non-physical) "particles" should be assigned IDUP=0 (i.e. the WZ 
particle in the example given in the MOTHUP description below) 
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• integer ISTUP(I) : status code 

-1 Incoming particle 

+1 Outgoing final state particle 

-2 Intermediate space-like propagator denning an x and Q 2 which should be preserved 
+2 Intermediate resonance, Mass should be preserved 
+3 Intermediate resonance, for documentation onlyf] 
-9 Incoming beam particles at time t = — oo 

The recoil from a parton shower (including photon emission) needs to be absorbed by particles 
in the event. Without special instructions, this can alter the mass of intermediate particles. 
The ISTUP flag +2 allows the user process to specify which intermediate states should have 
their masses preserved, i.e. for e + e~ — > Z°h° — ► qqbb, the Z° and h° would be flagged with 
ISTUP=+2. 

The primary application of the ISTUP=-2 status code is deep inelastic scattering (a negative 
number is chosen for this status code because the propagator in some sense can be thought 
of as incoming). See the example below. 

The status code ISTUP=-9 specifying incoming beams is not needed in most cases because 
the beam particle energy and identity is contained in the HEPRUP run information common 
block. The primary application of this status code will be non-collinear beams and/or runs for 
which the beam energy varies event by event (note that using the -9 status code to vary the 
machine energy may produce problems if the SHG is asked to combine separate processes). 
The use of ISTUP=-9 entries is optional, and is only necessary when the information in 
HEPRUP is insufficient. If entries with ISTUP=-9 are specified, this information will over- 
ride any information in HEPRUP. 

• integer M0THUP(2,I) : index of first and last mother 

For decays, particles will normally have only one mother. In this case either MOTHUP(2,I)=0 
or MOTHUP(2,I)=MOTHUP(l,I). Daughters of a 2 -> n process have 2 mothers. This 
scheme does not limit the number of mothers, but in practice there will likely never be more 
than 2 mothers per particle. 

The history (intermediate particles) will be used by the SHGs to decipher which combinations 
of particles should have their masses fixed and which particle decays should be "dressed" by 
the parton shower. Example: for qq' — > W~Zg — » l~vl + l~g, intermediate "particles" WZ, 
W, and Z could be specified with ISTUP=+2. Here the WZ "particle" would have its 
own entry in the common block with IDUP=0. The showering generator would preserve the 
invariant masses of these "particles" when absorbing the recoil of the parton shower. 

In a case like e + e~ — > proceeding via a 7* /Z°, where the matrix element contains an 

interference term between initial and final-state emission, this ambiguity in the parent-child 
history of the 7 has to be resolved explicitly by the user process. 

Color Flow 

A specific choice of color flow for a particular event is often unphysical, due to interference 
effects. However, SHGs require a specific color state from which to begin the shower — it 
is the responsibility of the user process to provide a sensible choice for the color flow of a 
particular event. 

4 Treatment of ISTUP(I)=+3 entries may be generator dependent (in particular see Ref. jllj for the 
special treatment in Pythia). 
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• integer IC0LUP(1 , 1) : integer tag for the color flow line passing through the color of the 
particle 

• integer IC0LUP(2,I) : integer tag for the color flow line passing through the anti-color of 
the particle 

The tags can be viewed as numbering the different color lines in the Nc — > oo limit. The 

color/anti-color of a particle are defined with respect to the physical time order of the process 

so as to allow a unique definition of color flow also through intermediate particles. 

This scheme is chosen because it has the fewest ambiguities, and when used with the history 

information, it supports Baryon number violation (an example is given below). 

To avoid confusion it is recommended that integer tags larger than MAXNUP (i.e. 500) are 

used. The actual value of the tag has no meaning beyond distinguishing the lines in a given 

process. 

Momentum and Position 

• double PUP(5,I) : lab frame momentum (P x , P y , P z , E, M) of particle in GeV 

The mass is the 'generated mass' for this particle, M 2 = E 2 — \p\ 2 (i.e. not necessarily equal 
to the on-shell mass). The mass may be negative, which denotes negative M 2 (i.e. M = 2 
implies M 2 = 4 whereas M = —2 implies M 2 = —4). 

Both E and M are needed for numerical reasons, the user should explicitly calculate and 
provide each one. 

• double VTIMUP(I) : invariant lifetime ct (distance from production to decay) in mm 
Combined with the directional information from the momentum, this is enough to determine 
vertex locations. Note that this gives the distance of travel for the particle from birth to 
death, in this particular event, and not its distance from the origin. 

Spin / Helicity 

• double SPINUP(I) : cosine of the angle between the spin-vector of particle I and the 3- 
momentum of the decaying particle, specified in the lab frame 

This scheme is neither general nor complete, but is chosen as the best compromise. The main 
foreseen application is r's with a specific helicity. Typically a relativistic r~ (t + ) from a W~ 
(W + ) has helicity -1 (+1) (though this might be changed by the boost to the lab frame), 
so SPINUP(I)= -1 (+1). The use of a floating point number allows for the extension to the 
non-relativistic case. Unknown or unpolarized particles should be given SPINUP(I)=9. The 
lab frame is the frame in which the four-vectors are specified. 
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Example: hadronic tt production 
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The t and i are given ISTUP=+2, which informs the SHG to preserve their invariant masses 
when showering and hadronizing the event. An intermediate s-channel gluon has been drawn 
in the diagram, but since this graph cannot be usefully distinguished from the one with a 
t-channel top exchange, an entry has not been included for it in the event record. 

The definition of a line as 'color' or 'anti-color' depends on the orientation of the graph. 
This ambiguity is resolved by defining color and anti-color according to the physical time 
order. A quark will always have its color tag ICOLUP(l,I) filled, but never its anti-color tag 
ICOLUP(2,I). The reverse is true for an anti-quark, and a gluon will always have information 
in both ICOLUP(l,I) and ICOLUP(2,I) tags. 

Note the difference in the treatment by the parton shower of the above example, and an 
identical final state, where the intermediate particles are not specified: 
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In this case the parton shower will evolve the b, b without concern for the invariant mass of 
any pair of particles. Thus the parton shower may alter the invariant mass of the Wb system 
(which may be undesirable if the Wb was generated from a top decay). 



Example: gg —> gg 




I ISTUP(I) IDUP(I) MOTHUP(l,I) MOTHUP(2,I) ICOLUP(l,I) ICOLUP(2,I) 



1 -1 21 (g) 501 502 

2 -1 21 (g) 502 503 

3 +1 21 (g) 1 2 501 504 

4 +1 21 (g) 1 2 504 503 
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Example: Baryon number violation in decays 
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Three "dangling" color lines intersect at the vertex joining the q,q,q' (and q,q, <?), which 
corresponds to a Baryon number source (sink) of +1 (-1), and will be recognizable to the 
SHGs. 
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Example: Baryon number violation in production 
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Example: deep inelastic scattering 
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For DIS, the x and q 2 of the 7 should not be altered by the parton shower, so the 7 is 
given ISTUP=-2. We have not specified the internal quark and gluon lines which will be 
dressed by the parton shower, such that the partonic event configuration may be drawn as 
follows, 




If information about the quark and gluon propagators is desired (i.e for human readability), 
then those entries may be included with status code ISTUP=+3. 
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